home *** CD-ROM | disk | FTP | other *** search
/ Light ROM 1 / LIGHT-ROM 1 (Amiga Library Services)(1994).iso / ffdisks / d944.lha / Lhf / Lhf.doc < prev    next >
Text File  |  1993-12-20  |  20KB  |  505 lines
  1.  
  2.       
  3.              Lhf v1.03 (CLI and Intuition archiver)
  4.              (c) Copyright 1993 by author Stefan Pampin.
  5.              Written using varios translators.
  6.  
  7.  0) This document
  8.  ---------------------------------------------------------------------------
  9.    This text is written in bad english. I'm sure that the extra work this 
  10.  will take you reading it will be rejectable consider to the work I spend to
  11.  write it. In all cases, the work is done for you.  
  12.  
  13.  1) Disclaimer
  14.  ---------------------------------------------------------------------------
  15.  The author cannot be held liable for the  suitability or  accuracy  of this
  16.  manual  and/or  the  program(s)  it  describes.   Any  damage  directly  or
  17.  indirectly caused by the use or misuse of  this manual  and/or the  program
  18.  it describes is the sole responsibility of the user her/him self.
  19.  
  20.  
  21.  2) Copyright/Distribution
  22.  ---------------------------------------------------------------------------
  23.  Lhf, (c) Copyright 1993 by author. All rights reserved. This
  24.  program is FREEWARE so no financial donations are required ( but welcome ).
  25.  This   program  may  be  freely  distributed  as  long  as all files, i.e.
  26.  documentation and executable(s) remain unchanged and are included  with the
  27.  distribution. (See the exception 3) below). Also no profit is to be made by
  28.  selling  this  program. You may not charge more than a resonable fee for the 
  29.  distribution.  This program may be distributed on disk magazines, cover 
  30.  disks etc.  When you do decide to distribute this program on a disk magazine
  31.  tell me before.
  32.  
  33.  
  34.  3) Electronic Distribution
  35.  ---------------------------------------------------------------------------
  36.  It is allowed for non-commercial BBSs to distribute  an archive  with  only
  37.  the following files in it:
  38.  
  39.     Lhf             - Main Program
  40.     Lhf.doc         - Main Program Manual (This file)
  41.     Lhf.info        - Main Program Icon.
  42.  
  43.     LhfEd        - Config Program
  44.     LhfEd.doc        - Config Program Manual
  45.     LhfEd.info      - Config Program Icon.
  46.  
  47.  You may NOT upload this or any  other form of  this  software on  BBSs that
  48.  claim copyrights on the uploaded material!
  49.  
  50.  
  51.  4) Requirements
  52.  ---------------------------------------------------------------------------
  53.   Lhf should run with all amigas version 1.3 or higher. One feature is
  54.  disabled for pre 2.0 users, 2.x style pattern maching. The colors will
  55.  look inverted on the 1.3 system. Perhaps I write specific versions for
  56.  pre and nonpre 2.0 users.
  57.   IT IS STILL UNTESTED UNDER OTHER SYSTEMS THAN 2.1 PAL. PLEASE IF YOU HAVE 
  58.  PROBLEMS WITH LHF UNDER YOUR SYSTEM LET ME KNOW, SO I CAN CORRECT IT.
  59.  SPECIALLY, NOTES ON SCREEN DIMENSIONS ARE WELCOME. I THINK THERE COULD BE
  60.  PROBLEMS WITH SYSTEMS MIXING BETWEEN PAL AND NTSC DISPLAY MODES.    
  61.  
  62.  5) Running Lhf
  63.  --------------------------------------------------------------------------    
  64.     You can start Lhf from either the CLI or the Workbench. Lhf have two
  65.  user interfaces. One is CLI and the other is Intuition driven. The CLI-
  66.  interface is invoked from CLI by entering one or more command lines
  67.  arguments. You can type 'Lhf ?' for a description (or see 7) below). If
  68.  no parameters are given when Lhf is started from CLI it will act like it
  69.  was started from WB, i.e. enter it's intuition interface described under
  70.  6) below. 
  71.  
  72.  6) Intuition Interface
  73.  ----------------------------------------------------------------------------
  74.     * --- GENERAL --- *
  75.  
  76.        Almost every gadget have diffrent action when they are selected
  77.     with the right or left mouse button (even arrow gadgets which pages
  78.     instead of scrolling when pressed with the right). 
  79.  
  80.     * --- ENTRY BOX ACTION--- *
  81.  
  82.      To enter a directory or a archive in a entry box simply press the
  83.     right mouse button over the entry. To select file entries press the
  84.     left mouse button over the entry. You can multi select (even with 
  85.     scroll) by holding the left button down and drag over the entries.
  86.     To unselect a entry simply select it again. See also [ ALL ] and
  87.     [ CLR ] about selection.
  88.      If a directory are selected the selection acts recursively on
  89.     the childs to that directory, but in some cases (such as the
  90.     [ RENAME ] function) this action is not taken. The action for
  91.     the user defined buttons are optional - act only on files,act
  92.     only on directory,act on both file and directories and finally
  93.     acts recursively or not.
  94.       If you enter a legal path that is a existing real path or a
  95.     existing path to a archive ev joined by slash with a archive
  96.     path,  that path file content will be showed.
  97.      With the textless gadgets you can switch between showing size
  98.     protection,date or time. Some archive directories are fictive,
  99.     why there creation date are not showen. 
  100.     
  101.      * --- TEXT BUTTON GADGET ACTION --- *
  102.  
  103.     
  104.        If you select a gadget (that is not obviosly specific to a
  105.     slider box) with left (right) mouse button, the box left (right)
  106.     box wish displays file entries will be called the source box. 
  107.            The right (left) box is the destination box.
  108.  
  109.     [ ALL ]
  110.            Selects all entries in the source box.
  111.  
  112.     [ CCOPY ]  
  113.            Function like [ COPY ]  but files are CLONE copied
  114.         instead of using the copy action you can select in a
  115.         option window.
  116.     
  117.     [ COPY ]
  118.            This function will copy FROM source box TO the dest-
  119.         ination box. Thus if the source and destination box both
  120.         are ordinary directories ,ordinary copy is performed. If
  121.         the boxes are archives, selected entries are effectively 
  122.         replaced in the destination arhive (without having to 
  123.         extract and recompress). If the boxes are of diffrent
  124.         kind extraction or compression are performed.
  125.         
  126.            Currently there is one restriction. Source and dest-
  127.         ination archives must be destinct.
  128.            If you want you can copy a archive to it self (like 
  129.         an archive backup) but ensure that the archive is packed
  130.         before and that no files are replaced. You can in all 
  131.         cases safely delete it from the archive.     
  132.         
  133.  
  134.     [ CMOVE ]
  135.            Function like [ CCOPY ] but files are moved.
  136.  
  137.     [ CLR ]
  138.            Unselects all entries in the source box.
  139.      
  140.     [ DELETE ]
  141.            This deletes the selected files and directories of a
  142.         ordinary or archive directory. In the latter case no pack -
  143.         ing are performed (to recieve minimal size you have to
  144.         [ PACK ] it). 
  145.     [ DUP ]
  146.            Duplicates the source box display to destination box
  147.         display.
  148.      
  149.     [ FREEUP ]
  150.            Reset the state of source box. All associated cathe
  151.         will be flushed.                   
  152.  
  153.     [ MAKEARC ]
  154.            This makes a archive (if not existed) in the source
  155.         box with the name you are ask to enter. 
  156.  
  157.     [ MAKEDIR ]
  158.            This makes a directory (if not existed) in the source
  159.         box with the name you are ask to enter. This even works
  160.         if you are in a archive.
  161.         
  162.     [ MOVE ]
  163.            Function like [ COPY ] but files are moved.
  164.  
  165.     [ OPTIONS ]
  166.            Will give you posibility to setup options. Diffrent 
  167.         options windows will appear depending on the mouse 
  168.         selection. With the save posibility, you can setup
  169.         your prefered default options for an unaltered copy
  170.         of Lhf (see Options below).
  171.     
  172.     [ PACK ]
  173.           This will pack those entries in the source box
  174.         representing an unoptimated archive. No compression
  175.         is performed only file operations.
  176.                     
  177.     [ RENAME ]
  178.            A string requester will ask you to enter a new name
  179.         for each selected file. This new name is relative to the
  180.         source box's path.
  181.     
  182.     [ REPAIR ]
  183.            Applies to the files selected in the source box. If 
  184.         they appear as a corrupted archive, the function will try 
  185.         to recover some data from them by repairing them.
  186.  
  187.     [ SCREEN ]
  188.            Toggle if Lhf should try to open a own screen for its
  189.         windows.
  190.     [ STORE ]
  191.            This require that the source box displays  a ordinary
  192.         directory and the destination box displays a archive
  193.         directory.  It stores files without any compression into
  194.         the archive. It is preferable if you wish to add a archive
  195.         as a simple file to another archive, since the compression
  196.         ratio, in general, will be better.     
  197.  
  198.     [ SWAP ]
  199.           This swaps the source and destination box.
  200.     
  201.     [ UPDATE ]
  202.            Update the source box. This can be nessasary due to
  203.         that the internal catche,external command action  or 
  204.         multitasking.
  205.  
  206.     [ <User defined> ]
  207.            With the program LhfEd you can add button gadgets that
  208.         calls external commands. Be sure to work with unmodified
  209.         (including crunched) copies of Lhf. See the documentation
  210.         file LhfEd.doc for more information.           
  211.     
  212.  7) CLI Interface
  213.  ----------------------------------------------------------------------------
  214.       The CLI usage is as follow:
  215.     
  216.     Lhf <command> <archive> [<target archive>] [<pattern> ..]
  217.     
  218.     You can type 'Lhf ?' for a list of available commands and options.
  219.     Also see the option section 8).
  220.  
  221.       Command and options are case sensitive.
  222.  
  223.       Options can be given anywhere on command line.
  224.       
  225.       Note that the home and destination directories (selected by the -h
  226.     resp. -d options) corresponds to what is displayed in the source resp.
  227.         destination box's string gadget. They both default to current dir. It
  228.     is important that any path name part that ending in the char ':' is
  229.      given here and not in the patterns.
  230.  
  231.       Pattern matching is allowed under 2.x and acts recusively. Thus '#?'
  232.     is every file and dirs in the directory and it's subdirectories.
  233.       If no patterns are specified when command is l (list) or x (extract)
  234.     all files in the archive are selected.
  235.       The extention .f is not needed and must be specified if it is used (
  236.     this allows you to name archives '.f' wich is the default name that
  237.     appear in the make-directory-requester).  
  238.  
  239.     Some examples:
  240.     --------------
  241.  
  242.     1) Lhf r Arc -hSrcPath -dDstPath #?.(c|h) MakeFile 
  243.        - Compress all C files and/or MakeFile in SrcPath and store (ev.
  244.          replace) the data in a sub dir DstPath to the archive. If DstPath
  245.              not already is an existing path in the archive it is created.
  246.            
  247.     2) Lhf x Arc -hSrcPath -dDstPath #?.(c|h)
  248.        - Extract all C files stored in the archive sub dir SrcPath to the
  249.          real path DstPath. If DstPath not already is an existing path it
  250.          is created before.
  251.      
  252.     3) Lhf x Arc
  253.        - Extract all files and directories in Arc to the current directory.       
  254.     
  255.     4) Lhf l Arc -hSubPath
  256.        - List all files and directories stored in the sub path 'SubPath' to
  257.          the archive 'Arc'.
  258.  
  259.     5) Lhf c Arc1 Arc2 Dir File
  260.        - Copy the file File and the directory Dir (and all it's files and
  261.          sub directories) in the archive Arc1 to the root directory of the
  262.          archive Arc2.
  263.  
  264.     6) Lhf d Arc -hPath Dir1 Dir2
  265.        - Delete the sub directories 'Path/Dir1' and 'Path/Dir2' (and all it's
  266.        files and sub dircetories) in the archive 'Arc'.
  267.       
  268.     7) Lhf p Arc
  269.        - Pack the archive 'Arc'.
  270.  
  271.  8) Options
  272.  ----------------------------------------------------------------------------
  273.            (The left button selected option window)
  274.           ------------------------------------------     
  275.    8.1) Compression options
  276.    -------------------------
  277.     1) Input buffer size (CLI option I), the I-value.    
  278.         If this buffer is suppressed by giving a value less than the S-value.
  279.            For small I-values input will be readed direcly into compression buffer
  280.        and it will function at a least factor by wich input are readed.
  281.  
  282.     2) Output buffer size (CLI option O) the O-value.    
  283.         If this buffer is small consider to the H-value it will function like a
  284.        least factor by wich output is written. A value of zero forces output with
  285.        no care of alignment and approximately the size of the H-value * 1.25.
  286.     
  287.     3) Huffman buffer size (CLI option H) the H-value.
  288.         The default size is best in most cases, but changing it can trim a few
  289.        bytes for the result. Note that it a word size.
  290.     
  291.     4) Buffer step size (CLI option S) the S-value.
  292.         This is the internal compression work step. Currently the progress
  293.        value and big deal of stubs is going throw each step. Therefore don't
  294.        select it to small. On the other size, the smallest value will give
  295.        the best compression but it is enoght that the ratio N/S is small.
  296.         Note that N is an even multipel of this size, why you can indirectly
  297.        change the N-value if you works from CLI.
  298.             
  299.     5) Maximal offset or Index size (CLI option N) the N-value.
  300.         These value will range from 1 to 32k in step of 512 bytes. A bigger
  301.        value will in general give better compression but can increase the
  302.        compression time for the worst cases dramatically. Most compressors
  303.        works with a static value. As a comparation lharc and lha works with
  304.        the values 4k resp 8k. Note that this value is a multipel 2 or more
  305.        of the S-value, why your CLI input may be changed.
  306.     
  307.     6) Hash tabel values (CLI option L) the L-values.
  308.         The following combinations are allowed.       
  309.                           
  310.            4 5 6 7 shift 
  311.         12 X - - -    
  312.         13 - X - -
  313.         14 - X X -
  314.         15 - X X X
  315.            bits
  316.  
  317.         From CLI a combination not allowed will be siently corrected.
  318.         This values thus not affect the compression ratio.                  
  319.         The bits-value affects memory usage (a block of 1<<bits words
  320.         must be allocated when compressing) and compression speed.
  321.         Reduce IO-buffers before reducing these if it is speed you want.
  322.         The shift value will in general be best as small as possible.
  323.         Typically use L15,5 for all cases but out of memory situations.
  324.         L12,4 is the most memory effectively value (but the slowest).            
  325.                
  326.    8.2) Decompression options
  327.    --------------------------
  328.     1) Input buffer size (CLI option R) the R-Value.
  329.        This is the buffer size input are readed with when extracting.
  330.     
  331.     2) Output buffer size (CLI option W) the W-Value.
  332.         This value must be at least as high as the N-value used when
  333.        compression occured. Currently no detection is possible so it
  334.        defaults to a W-value of 32k (the maximal N-value) for smaller
  335.        values.
  336.  
  337.    8.3) Workdirectory (CLI option w)
  338.   ---------------------------------
  339.      This directory can be used to store temporary files when packing
  340.         archives or preforming a user-defined button command on an on files
  341.     in an archive. Typically hd owners assign a directory on there hd.
  342.     It is saved with the other options.          
  343.           
  344.     
  345.            (Right button selected option window)
  346.           ---------------------------------------     
  347.  
  348.   8.4) Catche lines option
  349.   ------------------------
  350.     This option give you possibility to catch Lhf's output and later
  351.        scroll it. Currently lines are stored unpacked (80 bytes each) so
  352.        take care that this option not eats up your memory.
  353.   
  354.   8.5) Gadget functional delays
  355.   -----------------------------
  356.      This enable syncronousation to your system (or your self).
  357.   
  358.   8.6) Copy/Store action
  359.   ----------------------
  360.     1) Copy action. 
  361.        With these you can select your perfered [COPY] action
  362.      (r command action in CLI). When [CCOPY] (or the -c option are
  363.      used) all these is set.
  364.     
  365.     2) Store action.
  366.        With these you can set up if you want to store things in the
  367.      archive or not. This can be handy if you planing to [STORE] 
  368.      (or use the -s option) and afterwords compress the whole archive.
  369.      
  370.   8.7) Save option        
  371.   ----------------
  372.     By enter a pathname to a unaltered (even packed) Lhf copy you can
  373.     save all options that can be changed from a option window (or CLI)
  374.     as the default values. These values applies to CLI usages also.
  375.       Note that the originally Lhf program is altered an there is no
  376.     way to get back the previous values. So work with an copy of your
  377.     originally Lhf program.
  378.  
  379.   8.8) CLI only options
  380.   ---------------------
  381.     1) d-option
  382.         Selects destination directory. 
  383.     2) h-option
  384.         Selects home directory. 
  385.     3) i-option
  386.         With these you can specify an include file with patterns
  387.          separated with white spaces. No options are parsed
  388.          in the file.
  389.     4) '-'-option
  390.         By double express introducing '-' in an pattern, you
  391.          suppress the status as an option introducer and it will
  392.          be parsed correctly as a filepattern.
  393.          
  394.                
  395.  9) Memory Usage
  396.  ----------------------------------------------------------------------------
  397.     Note that:
  398.     - I,O,L values not affects compression.
  399.     - Totally 5*N bytes of memory is allocated when compressing.
  400.     
  401.     I working on a option  window that are less technical inwich you
  402.     can optimate with resp to memory usage.     
  403.  
  404.  10) Need of Packing/Reapairing
  405.  ----------------------------------------------------------------------------
  406.      After deletion from an archive unused  space is left at the end
  407.     of the archive. To remove these area one must create a temporary
  408.     archive (if there is a another way please tell me!). These oper-
  409.     ation is ignored when deleting files from an archive because when
  410.     you later add to the library the unused space is first overwritten.
  411.     Note that if you copy to a archive and some of the files you copy
  412.     already exist in the archive, deletion are performed so to be sure
  413.     that the archive is of minimal size you have to pack it. It is 
  414.     effectively to trie to pack an already packed archive.
  415.     
  416.      If you have had any io trouble with an archive youh should repair it.
  417.         currently this function is not so powerful but it creates a legal
  418.     archive structure.      
  419.  
  420.  11) Window Title
  421.  ----------------------------------------------------------------------------
  422.      The main window title shows   
  423.         aa | bb | cc 
  424.     where
  425.        aa = free space (KB) in left box unit
  426.        bb = free memory (KB)
  427.        cc = free space (KB) in right box unit.
  428.     
  429.       
  430.  12) Ctrl-F Action
  431.  ----------------------------------------------------------------------------
  432.      When <Ctrl-F> is pressed during some operations a break will
  433.        occur. In intuition mode a requester will bring up and ask you if 
  434.        you want to break the proceeding operation. If you incist a break 
  435.        will occur. 
  436.     The break is friendly to the file and archive structures but beware
  437.        that when you indeed are replacing files in an archive, the old copies
  438.        can be loosed (have to truncate previosly stored files/directories 
  439.        before a copy can be performed). The sources will always correspond to
  440.        what was added or not (nice if you MOVEs). The break are consider as 
  441.        an legal end of source data, so no error messages will occur only an
  442.        break message.    
  443.      
  444.  13) Compression Algorithms
  445.  ---------------------------------------------------------------------------      
  446.     The algorithms used by Lhf are completely developed and written by
  447.      the author. Many basic ideas was taken from other algoritms but the
  448.      final result is more due to me self and random (a bug leaded me into
  449.      what seems to be the right direction). The main routines are written
  450.      in assembler and are optimated for a 16-bit machine.       
  451.  
  452.  14) Limits
  453.  ----------------------------------------------------------------------------
  454.    Lhf is designed to work with out limits with a few exeption:
  455.   - All paths are currently supposed to be less than 288 bytes.
  456.   - The stack size is expected to be at least 4k
  457.   - The total command line size when preforming a user-defined button
  458.     must be atmost 1k.
  459.  
  460.   A practical note:
  461.     This archive store files as consequetive words. The tree structure is 
  462.     fictive. Therfore don't make to big archives for speed (and space) 
  463.     reasons. They works, but in an inefficient way.
  464.     
  465.  15) History
  466.  ----------------------------------------------------------------------------
  467.  
  468.  V1.00 (27-Jan-93)    Merged together my archiver and my dir utility, by
  469.             redirection of the CLI output in intuition mode.
  470.  
  471.  V1.01 (18-Mar-93)    Changed the compression algoritms.
  472.             Option windows added.
  473.             2.x supported pattern matching added.
  474.  
  475.  V1.02 (19-Aug-93)    Removed some statistical options.
  476.             Reduced the code size.
  477.             Added code to support LhfEd.
  478.             - Now it have been practical!
  479.      
  480.  V1.03 (13-Oct-93)    Interface with LhfEd improved.
  481.             
  482.  
  483.  16) Bugs
  484.  ----------------------------------------------------------------------------
  485.  - Version 1.02 did not stored dates correctly. Fixed with V1.03
  486.  
  487.  - If there are any bug in the latest version, let me know please.
  488.  
  489.  
  490.  17) Author
  491.  ----------------------------------------------------------------------------
  492.  
  493.    Any question about distribution rights, bug reports, suggestions, criticisms,
  494.  contributions, ideas, gifts, etc. can be sent to me (maybe you can receive a 
  495.  later version):
  496.  
  497.  Stefan Pampin
  498.  Timmermansgrand 2 ,4 tr
  499.  S-118 65  Stockholm
  500.  Sweden
  501.  
  502.  
  503.  
  504.  
  505.